Add a "Disabling features" reference page - #6549
Open
ctondreau wants to merge 2 commits into
Open
Conversation
Ask AI analytics show "how do I turn off X" is one of the most common question clusters on the docs site, and several readers had the right YAML and still couldn't get there. The settings exist but are scattered across Site settings, the API Reference layout page, and the Dashboard. Adds /learn/docs/configuration/disabling-features, a router page that collects the documented off switches and links to each canonical page. It leads with the confusion the analytics surfaced most: Ask Fern is a Dashboard toggle, `page-actions.options.ask-ai` only hides the page action button, and `ai-search` configures Ask Fern without enabling or disabling it. Also flags that the MCP server toggle lives under `page-actions` despite controlling an endpoint, and that `disable-explorer-proxy` is not an off switch for the API Explorer. Cross-links from the Configuration overview, Site settings, Ask Fern overview, and Hiding content. Co-Authored-By: Claude <noreply@anthropic.com>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| <Steps> | ||
| <Step title="Enable in the Dashboard"> | ||
| Open the [Fern Dashboard](https://dashboard.buildwithfern.com/). Navigate to the **Settings** tab and click **Enable** on the Ask AI card. | ||
| Open the [Fern Dashboard](https://dashboard.buildwithfern.com/). Navigate to the **Settings** tab and click **Enable** on the Ask AI card. The same card [turns Ask Fern off](/learn/docs/configuration/disabling-features#ask-fern-and-the-ask-ai-button), which is separate from hiding the **Ask AI** page action button in `docs.yml`. |
Contributor
There was a problem hiding this comment.
[Microsoft.UIVerbs] Use 'select' instead of the input-specific verb 'click'.
| | Ask Fern itself: AI search and the side panel | **Settings** > **Ask AI** card in the Dashboard | | ||
| | The **Ask AI** page action button | `page-actions.options.ask-ai: false` in `docs.yml` | | ||
|
|
||
| The [`ai-search` key](/learn/docs/configuration/site-level-settings#ask-fern-configuration) configures Ask Fern once it's enabled, setting PII masking, additional datasources, and the system prompt. It has no enable or disable property, so `ai-search: {}` leaves Ask Fern running with its default behavior. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'PII' has no definition.
| | [AI-generated examples](/learn/docs/ai-features/ai-examples) in the API Reference | `ai-examples.enabled: false` | | ||
| | The [directive prepended to pages served to agents](/learn/docs/ai-features/llms-txt) | `agents.page-directive: ""` | | ||
|
|
||
| `settings.disable-explorer-proxy: true` is not an off switch for the Explorer. It keeps the Explorer running and sends requests directly to your API instead of through Fern's proxy, which requires CORS on your API. To turn the Explorer off, use an empty `playground.environments` list. |
Contributor
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'isn't' instead of 'is not'.
Contributor
|
🌿 Preview your docs: https://fern-preview-docs-disabling-features-reference.docs.buildwithfern.com/learn Here are the markdown pages you've updated: |
| For OpenAPI specs, the API Explorer is enabled by default for all endpoints. You can disable it globally or per endpoint using the [`x-fern-explorer`](/learn/api-definitions/openapi/extensions/api-explorer-control) extension. This is commonly used to disable the Explorer for destructive operations, payment processing, or admin-only endpoints. | ||
| For OpenAPI specs, the API Explorer is enabled by default for all endpoints. To turn it off globally or per endpoint, use the [`x-fern-explorer`](/learn/api-definitions/openapi/extensions/api-explorer-control) extension. This is commonly used to disable the Explorer for destructive operations, payment processing, or admin-only endpoints. | ||
|
|
||
| Setting [`disable-explorer-proxy`](/learn/docs/configuration/site-level-settings#settingsdisable-explorer-proxy) does not turn the Explorer off. It keeps the Explorer running and routes requests directly to your API instead of through Fern's proxy. |
Contributor
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'doesn't' instead of 'does not'.
| <Steps> | ||
| <Step title="Enable in the Dashboard"> | ||
| Open the [Fern Dashboard](https://dashboard.buildwithfern.com/). Navigate to the **Settings** tab and click **Enable** on the Ask AI card. | ||
| Open the [Fern Dashboard](https://dashboard.buildwithfern.com/). Navigate to the **Settings** tab and click **Enable** on the Ask AI card. Return to this card to [disable Ask Fern](#disable-ask-fern) later. |
Contributor
There was a problem hiding this comment.
[Microsoft.UIVerbs] Use 'select' instead of the input-specific verb 'click'.
|
|
||
| ## Disable Ask Fern | ||
|
|
||
| To turn Ask Fern off, open the [Fern Dashboard](https://dashboard.buildwithfern.com/), navigate to the **Settings** tab, and click **Disable** on the Ask AI card. This removes AI search and the side panel from your site. There is no `docs.yml` equivalent — the [`ai-search` key](/learn/docs/configuration/site-level-settings#ask-fern-configuration) configures Ask Fern once it's enabled, so setting `ai-search: {}` leaves it running with its default behavior. |
Contributor
There was a problem hiding this comment.
[Microsoft.UIVerbs] Use 'select' instead of the input-specific verb 'click'.
| ask-ai: false | ||
| ``` | ||
|
|
||
| Ask Fern stays reachable everywhere else it appears, including the search bar and the [standalone search widget](/learn/docs/ai-features/ask-fern/search-widget). |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Microsoft.OxfordComma] Use the Oxford comma in ', including the search bar and the standalone search widget.'.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Pulling Ask AI analytics for the last 30 days (1,115 conversations, 74.5% resolved), "how do I turn off X" is one of the most consistent question clusters on the site. A sample of ~150 queries turned up readers trying to disable the Ask AI button, the MCP server, the API Explorer, Wiremock test generation, the Fern badge, and CSP.
The notable part: several had nearly the right YAML and still couldn't get there. One reader wrote:
Every setting they used is real and documented. The gap is that they're scattered across Site settings, the API Reference layout page, and the Dashboard, and that
ask-ai: falsedoesn't do what the name suggests.What
Adds
/learn/docs/configuration/disabling-featuresunder Configuration, next to Site settings and Page settings. It's a router page: each entry says what to set and links to the canonical page rather than restating it.It leads with the confusion the analytics surfaced most:
docs.ymlkey disables it.page-actions.options.ask-ai: falsehides the page action button only. It does not disable Ask Fern.ai-searchconfigures Ask Fern; it has no enable/disable property.ai-search: {}leaves it running with defaults.Two other traps worth naming:
page-actions.optionsdespite controlling an endpoint rather than a button.settings.disable-explorer-proxyis not an off switch for the API Explorer — it keeps the Explorer running and bypasses Fern's proxy. Turning the Explorer off is an emptyplayground.environmentslist.Cross-links added from Configuration overview (new card), Site settings (Ask Fern configuration), Ask Fern overview (enable step), and Hiding content (features vs. content).
Scope notes
playground.environments: []failing when set on an- apientry inside a tab in a product YAML. That may be a real bug, but I couldn't confirm the mechanism from the docs, so the page doesn't speculate. Worth a separate look.permissions-policyon the docs site, and disabling Wiremock test generation for the TypeScript SDK generator. Both came up in Ask AI. Removing the Fern badge from generated SDKs iswhitelabelingenerators.yml, which is SDK product territory rather than this page.zhoverlay doesn't mirror every English page, so this follows existing practice.fern checknot run — the CLI isn't installed in this environment. Links were verified by hand against the YAML config perAGENTS.md, and every anchor target was confirmed to be a real##/###heading.Generated with Claude Code